Inside Macintosh: QuickTime

Previous | Chapter Top | Chapter Contents | Next

CompressPicture

The CompressPicture function compresses a single-frame image stored as a picture structure and places the result in another picture. If a picture with multiple pixel maps and other graphical objects is passed, the pixel maps will be compressed individually and the other graphic objects will not be affected.

pascal OSErr CompressPicture (PicHandle srcPicture,
                                         PicHandle dstPicture,
                                         CodecQ quality, CodecType cType);


srcPicture

Contains a handle to the source image, stored as a picture.

dstPicture

Contains a handle to the destination for the compressed image. The compressor resizes this handle for the result data.

quality

Specifies the desired compressed image quality. See "Compression Quality Constants," for valid values.

cType

Specifies a compressor type. You must set this parameter to a valid compressor type (see Table 3 for a list of the available compressor types). If the value passed in is 0, or 'raw ' , and the source picture is compressed, the destination picture is created as an uncompressed picture and does not require QuickTime to be displayed.

FCompressPicture

The FCompressPicture function compresses a single-frame image stored as a picture structure and places the result in another picture. If a picture with multiple pixel maps and other graphical objects is passed, the pixel maps will be compressed individually and the other graphic objects will not be affected.

pascal OSErr FCompressPicture (PicHandle srcPicture,
                                         PicHandle dstPicture,
                                         short colorDepth,
                                         CTabHandle ctable,
                                         CodecQ quality,
                                         short doDither,
                                         short compressAgain,
                                         ICMProgressProcRecordPtr progressProc,
                                         CodecType cType,
                                         CompressorComponent codec);


srcPicture

Contains a handle to the source image, stored as a picture.

dstPicture

Contains a handle to the destination for the compressed image. The compressor resizes this handle for the result data.

colorDepth

Specifies the depth at which the image is to be compressed. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor information structure returned by the GetCodecInfo function (see "Getting Information About Compressor Components," which begins on Getting Information About Compressor Components , for more information).

ctable

Contains a handle to a custom color lookup table. Your program may use this parameter to indicate a custom color lookup table to be used with this image. If the value of the colorDepth parameter is less than or equal to 8 and the custom color lookup table is different from that of the source pixel map (that is, the ctSeed field values differ in the two pixel maps), the compressor remaps the colors of the image to the custom colors. If you set the colorDepth parameter to 16, 24, or 32, the compressor stores the custom color table with the compressed image. The compressor may use the table to specify the best colors to use when displaying the image at lower bit depths. The compressor ignores the ctable parameter when colorDepth is set to 33, 34, 36, or 40. If you set this parameter to nil , the compressor uses the color lookup table from the source pixel map.

quality

Specifies the desired compressed image quality. See "Compression Quality Constants," for available values.

doDither

Indicates whether to dither the image. Use this parameter to indicate whether you want the image to be dithered when it is displayed on a lower-resolution screen. The following constants are available:

defaultDither

Indicates that the dithering in the source file is to be respected.

forceDither

Indicates that the specified image should be dithered whether the source uses dithering or not.

suppressDither

Indicates that dithering should not be used in any case. The ability to suppress dithering can be useful if, for example, you have a 32-bit color JPEG image drawn into a 8-bit buffer with a custom color table from the image. In that case, dithering would not be necessary and probably not desirable, particularly if the buffer were to be compressed with the graphics compressor.

compressAgain

Indicates whether to recompress compressed image data in the picture. Use this parameter to control whether any compressed image data that is in the source picture should be decompressed and then recompressed using the current parameters. Set the value of this parameter to true to recompress such data. Set the value of the parameter to false to leave the data as it is. Note that recompressing the data may have undesirable side effects, including image quality degradation.

progressProc

Points to a progress function structure. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress (see "Progress Functions," for more information about progress functions). If you have not provided a progress function, set this parameter to nil . If you pass a value of -1, you obtain a standard progress function.

cType

Specifies a compressor type. You must set this parameter to a valid compressor type (see Table 3 for a list of the available compressor types). If the value passed in is 0, or 'raw ' , the resulting picture is not compressed and does not require QuickTime to be displayed.

codec

Contains a compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first compressor of the specified type

bestSpeedCodec

Choose the fastest compressor of the specified type

bestFidelityCodec

Choose the most accurate compressor of the specified type

bestCompressionCodec

Choose the compressor that produces the smallest resulting data

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

CompressPictureFile

The CompressPictureFile function compresses a single-frame image stored as a picture file (PICT file) and places the result in another picture file.

pascal OSErr CompressPictureFile (short srcRefNum,
                                          short dstRefNum,
                                          CodecQ quality,
                                          CodecType cType);


srcRefNum

Contains a file reference number for the source PICT file.

dstRefNum

Contains a file reference number for the destination PICT file. Note that the compressor overwrites the contents of the file referred to by dstRefNum . You must open this file with write permission. The destination file can be the same as the source file specified by the srcRefNum parameter.

quality

Specifies the desired compressed image quality. See "Compression Quality Constants" for available values.

cType

Specifies a compressor type. You must set this parameter to a valid compressor type (see Table 3 for a list of the available compressor types). If the value passed in is 0, or 'raw ' , and the source picture is compressed, the destination picture is created as an uncompressed picture and does not require QuickTime to be displayed.

FCompressPictureFile

The FCompressPictureFile function compresses a single-frame image stored as a picture file (PICT file) and places the result in another picture file.

pascal OSErr FCompressPictureFile (short srcRefNum,
                                         short dstRefNum, short colorDepth,
                                         CTabHandle ctable, CodecQ quality,
                                         short doDither,
                                         short compressAgain,
                                         ICMProgressProcRecordPtr progressProc,
                                         CodecType cType,
                                         CompressorComponent codec);


srcRefNum

Specifies a file reference number for the source PICT file.

dstRefNum

Specifies a file reference number for the destination PICT file. Note that the compressor overwrites the contents of the file referred to by dstRefNum . You must open this file with write permissions. The destination file may be the same as the source file specified by the srcRefNum parameter.

colorDepth

Specifies the depth at which the image is to be compressed. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor capability structure returned by the GetCodecInfo function (see "Getting Information About Compressor Components," which begins on Getting Information About Compressor Components , for more information).

ctable

Contains a handle to a custom color lookup table. Your program may use this parameter to indicate a custom color lookup table to be used with this image. If the value of the colorDepth parameter is less than or equal to 8 and the custom color lookup table is different from that of the source pixel map (that is, the ctSeed field values differ in the two pixel maps), the compressor remaps the colors of the image to the custom colors. If you set the colorDepth parameter to 16, 24, or 32, the compressor stores the custom color table with the compressed image. The compressor may use the table to specify the best colors to use when displaying the image at lower bit depths. The compressor ignores the ctable parameter when colorDepth is set to 33, 34, 36, or 40. If you set this parameter to nil , the compressor uses the color lookup table from the source pixel map.

quality

Specifies the desired compressed image quality. See "Compression Quality Constants" for available values.

doDither

Indicates whether to dither the image. Use this parameter to indicate whether you want the image to be dithered when it is displayed on a lower-resolution screen. The following constants are available:

defaultDither

Indicates that the dithering in the source file is to be respected.

forceDither

Indicates that the specified image should be dithered whether the source uses dithering or not.

suppressDither

Indicates that dithering should not be used in any case. The ability to suppress dithering can be useful if, for example, you have a 32-bit, color JPEG image drawn into an 8-bit buffer with a custom color table from the image. In that case, dithering would not be necessary and probably not desirable, particularly if the buffer were to be compressed with the graphics compressor.

compressAgain

Indicates whether to recompress compressed image data in the picture. Use this parameter to control whether any compressed image data that is in the source picture should be decompressed and then recompressed using the current parameters. Set the value of this parameter to true to recompress such data. Set the value of this parameter to false to leave the data as it is. Note that recompressing the data may have undesirable side effects, including image quality degradation.

progressProc

Points to a progress function structure. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress (see "Progress Functions" for more information about progress functions). If you have not provided a progress function, set this parameter to nil . If you pass a value of -1, you obtain a standard progress function.

cType

Specifies a compressor type. You must set this parameter to a valid compressor type (see Table 3 for a list of the available compressor types). If the value passed in is 0, or 'raw ' and the source picture is compressed, the destination picture is created as an uncompressed picture and does not require QuickTime to be displayed.

codec

Contains a compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first compressor of the specified type

bestSpeedCodec

Choose the fastest compressor of the specified type

bestFidelityCodec

Choose the most accurate compressor of the specified type

bestCompressionCodec

Choose the compressor that produces the smallest resulting data

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

DrawPictureFile

The DrawPictureFile function draws an image from a specified picture file (PICT file) in the current graphics port. Your program also specifies the destination rectangle for the image.

pascal OSErr DrawPictureFile (short refNum, const Rect *frame,
                                          ICMProgressProcRecordPtr progressProc);


refNum

Contains a file reference number for the source PICT file.

frame

Contains a pointer to the rectangle into which the image is to be loaded. The compressor scales the source image to fit into this destination rectangle.

progressProc

Points to a progress function structure. During the operation, the draw function may occasionally call a function you provide in order to report its progress (see "Progress Functions," for more information about progress functions). If you have not provided a progress function, set this parameter to nil . If you pass a value of -1, you obtain a standard progress function.

DrawTrimmedPicture

The DrawTrimmedPicture function draws an image that is stored as a picture into the current graphics port and trims that image to fit a region you specify.

pascal OSErr DrawTrimmedPicture (PicHandle srcPicture,
                                         const Rect *frame, RgnHandle trimMask,
                                         short doDither,
                                         ICMProgressProcRecordPtr progressProc);


srcPicture

Contains a handle to the source image; stored as a picture.

frame

Contains a pointer to the rectangle into which the decompressed image is to be loaded.

trimMask

Contains a handle to a clipping region in the destination coordinate system. The decompressor applies this mask to the destination image and ignores any image data that fall outside the specified region. Set this parameter to nil if you do not want to clip the source image. In this case, this function acts like QuickDraw's DrawPicture routine, but it also allows you to control dithering and assign a progress function. (See Inside Macintosh: Imaging for more on DrawPicture .)

doDither

Indicates whether to dither the image. Use this parameter to indicate whether you want the image to be dithered when it is displayed on a lower-resolution screen. The following constants are available:

defaultDither

Indicates that the dithering in the source file is to be respected.

forceDither

Indicates that the specified image should be dithered whether the source uses dithering or not.

suppressDither

Indicates that dithering should not be used in any case. The ability to suppress dithering can be useful if, for example, you have a 32-bit, color JPEG image drawn into an 8-bit buffer with a custom color table from the image. In that case, dithering would not be necessary and probably not desirable, particularly if the buffer were to be compressed with the graphics compressor.

progressProc

Points to a progress function structure. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress (see "Progress Functions," for more information about progress functions). If you have not provided a progress function, set this parameter to nil . If you pass a value of -1, you obtain a standard progress function.

DrawTrimmedPictureFile

The DrawTrimmedPictureFile function draws an image that is stored as a picture file (PICT file) into the current graphics port and trims that image to fit a region you specify.

pascal OSErr DrawTrimmedPictureFile (short srcRefnum,
                                         const Rect *frame,
                                         RgnHandle trimMask,
                                         short doDither,
                                         ICMProgressProcRecordPtr progressProc);


srcRefNum

Contains a file reference number for the source PICT file.

frame

Contains a pointer to the rectangle into which the decompressed image is to be loaded.

trimMask

Contains a handle to a clipping region in the destination coordinate system. The decompressor applies this mask to the destination image and ignores any image data that fall outside the specified region. Set this parameter to nil if you do not want to clip the source image. In this case, this function acts like the DrawPictureFile function, which is described on DrawPictureFile .

doDither

Indicates whether to dither the image. Use this parameter to indicate whether you want the image to be dithered when it is displayed on a lower-resolution screen. The following constants are available:

defaultDither

Indicates that the dithering in the source picture file is to be respected.

forceDither

Indicates that the specified image should be dithered whether the source uses dithering or not.

suppressDither

Indicates that dithering should not be used in any case. The ability to suppress dithering can be useful if, for example, you have a 32-bit color JPEG image drawn into an 8-bit buffer with a custom color table from the image. In that case, dithering would not be necessary and probably not desirable, particularly if the buffer were to be compressed with the graphics compressor.

progressProc

Points to a progress function structure. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress (see "Progress Functions," for more information about progress functions). If you have not provided a progress function, set this parameter to nil . If you pass a value of -1, you obtain a standard progress function.

GetPictureFileHeader

The GetPictureFileHeader function extracts the picture frame (the picFrame rectangle in the picture structure) and file header from a specified picture file (PICT file). Your program can use this information to determine how to draw an image without having to read the picture file.

pascal OSErr GetPictureFileHeader (short refNum, Rect *frame,
                                         OpenCPicParams *header);


refNum

Contains a file reference number for the source PICT file.

frame

Contains a pointer to a rectangle that is to receive the picture frame rectangle of the picture file. This function places the picFrame rectangle from the picture structure into the rectangle referred to by the frame parameter. If you are not interested in this information, pass nil in this parameter.

header

Contains a pointer to an OpenCPicture parameters structure. The GetPictureFileHeader function places the header from the specified picture file into the structure referred to by the header parameter. Note that this function always returns a version 2 header. If the source file is a version 1 PICT file, the GetPictureFileHeader function converts the header into version 2 format before returning it to your application. See Inside Macintos h: Imaging for more information about picture headers and the OpenCPicture function. If you are not interested in this information, pass nil in this parameter.